+=====================+
| BD MultiGunFix v2.5 |
+=====================+

Author:
======
Big Dawg KS

Credits:
-------
Big Dawg KS - scripts
oyman - testing
The D - testing

Thanks:
------
Sickboy
Killswitch

Changelog:
=========
v2.5
-----
-reworked scripts to take advantage of changes to the fired EH with recent beta builds
--this should fix any remaining problems with "one sided" rockets
--this also makes use of 'originalMuzzleEnd' unneccessary
-improved method for detecting ammo count for weapons on any turret
-added BAF vehicles
--Apache AH1
--Wildcat AH11

v2.3
-----
-fixed possibility for rockets to be incorrectly placed (all vehicles)

v2.2
-----
-fixed possibility for Mi24 rockets to be incorrectly placed

v2.1
-----
-fixed script error

v2.0
-----
-added vehicles from OA
--M2A2
--M2A3
--M6
--AH6
--Mi17 (CZ)
--Stryker (TOW)
--L39
-added feature: convergence
-added support for OA zeroing
-improved MP compatability
-additional config definitions for addons

v1.4
-----
-fixed minor script error
-reworked MP compatability
-improved support for addons

v1.3
-----
-added more BIS vehicles
-added support for addons

v1.0
-----
Initial Release

Description:
===========
Multiple Muzzles:
----------------
In ArmA 2 (prior to OA), there is no native support for multiple muzzle positions for vehicle weapons. This addon provides
a set of scripts both for existing BIS vehicles and for new addon vehicles that allows the proper simulation of multiple
muzzle/launch positions for any type of weapon.

As of Operation Arrowhead, the engine natively supports multiple muzzles (at least for bullet firing weapons), but this
addon is still compatable with those vehicles that use this new native feature, and can still be used for addons if
the native solution is not possible/preferable.

Convergence:
-----------
As of v2.0 of this addon, there is a new feature that allows weapons with multiple muzzle/launch positions to converge
on a single point at a given distance. This feature is present for ArmA 2 stand alone, but currently the range can not
be adjusted by the player. In Operation Arrowhead, this feature is tied to the native zeroing system; your rounds will
converge at the range at which you are currently zeroed. Note: some BIS vehicles that use convergence do not allow
zeroing. In this case, a fixed convergence range is used.

Those vehicles that do not currently use zeroing are the AH-6J and Tunguska, which converge by default at 400 and 500
meters respectively.

BIS Vehicles:
------------
This addon contains a few simple scripts that fix the simulation of bullets and missiles firing from the correct places on BIS vehicles.
The following vehicles are effected:

ArmA 2 vehicles:
-Mi-24 (all factions & varients)
-ZU-23 (all factions)
-Shilka (all factions)
-Tunguska
-Ural ZU-23 (all factions)
-BRDM-2 ATGM (all factions)
-Avenger HMMWV
-BM-21 GRAD (all factions)
-MLRS
-Igla AA Pod
-Stinger AA Pod
-AH-1Z
-AH-64
-A-10
-AV-8B
-UH-1Y
-BMP-3
-Mi-8MTV
-Ka-52 (both varients)
-Su-25 (all factions & varients)

OA Vehicles (of those not included in ArmA 2):
-M2A2 Bradley
-M2A3 Bradley
-M6 Linebacker
-Mi-171Sh (CZ)
-AH-6J
-L-39
-Stryker (TOW)

BAF Vehicles:
-Apache AH-1
-Wildcat AH-11

All gun barrels, rocket and missile launchers are correctly simulated for these vehicles.

Addons:
------
In addition, this addon includes a system that allows addon makers to easily enable multiple barrels/launch positions for new vehicles using
only model and config changes and little scripting knowledge.
How to use the system for new vehicles:
1. Create a memory point with a named selection in your model for each position you want the projectiles to be fired from
2. In the vehicle's config, define a class called BD_MultiGunFix
3. In class BD_MultiGunFix, you can define any number of 'weapon groups'. A weapon group is one set of guns or launchers that when fired,
the projectiles will be distributed among all the positions defined in that group. For example, if your vehicle has 4x30mm cannons and 2 missile
launchers, you would have a 30mm cannon group and a missile group. The groups are defined as classes
4. For each group class, define an array called 'weapons' and an array called 'positions'. The positions array contains all of the selection names
you defined in your model that you want this group to use, and the weapons array contains the classnames of all the weapons that will use
that set of positions.
5. The last step is to simply ensure that BD_MultiGunFix is installed and loaded when you start up ArmA 2. Using this system will not make
your addon require BD_MultiGunFix, rather when the user is running your addon while using BD_MultiGunFix the fix will be applied, and
if not your addon will function normally without the fix (with a limit of only 1 firing position per weapon type).

Primary Config Definitions:
--------------------------

 weapons[]	- array of weapon classnames (strings):
		for which weapons this configuration should be used

 positions[]	- array of model selections (strings):
  		which memory points of all new muzzles

Optional Config Definitons:
--------------------------

 originalMuzzleEnd	- model selection (string):
			original muzzle position (helps improve "catching" the projectile)
			Note: no longer serves any purpose as of v2.5

 preMgFixCode		- code (as string):
			optional code you want to call (will be called by MgFix scripts)
			before MgFix repositions the projectile; useful for scripts that
			are dependent on the projectile being in its original position.
			Note: if you use this, make sure you check in your code if
			MultiGunFix is enabled (using global variable 'BD_MgFix_Init')
			to avoid calling it twice (ie. once from MgFix and again by your
			regular fired eventhandler).

 zeroRanges[]		- array of numbers:
			(ArmA 2 only) possible zero (convergence) ranges
			Note: currently there is no way to adjust zeroing in ArmA 2,
			only the default value will be used (see defaultZeroIndex)

 defaultZeroIndex	- number:
			(ArmA 2 only) index of zeroRanges to use as default zeroing
			Note: currently there is no way to adjust zeroing in ArmA 2,
			only the default value will be used

 turretPath		- string:
			(OA only) the turret path (as it is used in turretUnit) of the
			gunner who will use this configuration; used to get current zeroing

 applyConvergenceOnly	- boolean (number):
			(OA only) if set to true (not 0), then MultiGunFix data will
			only be used for convergence; this is if you want to use OA's
			native support for multiple muzzles instead of MultiGunFix's
			scripted workaround for positioning the projectiles, but still
			want to use convergence from MultiGunFix

Config Example:
--------------

class CfgVehicles {
	...
	class MyVehicle { // your vehicle class
		...
		class BD_MultiGunFix {

			// this example is for ArmA 2
			class 30mm {
				weapons[]={"30mmCannon"};
				positions[]={"30mmMuzzle1","30mmMuzzle2","30mmMuzzle3","30mmMuzzle4"};

				originalMuzzleEnd="konec hlavne";	// obsolete as of v2.5
				zeroRanges[]={300,400,500};
				defaultZeroIndex=1;
			}

			// this example is for Operation Arrowhead
			class Missiles {
				weapons[]={"MissileLauncher"};
				positions[]={"missilePosition1","missilePosition2"};

				originalMuzzleEnd="konec hlavne";	// obsolete as of v2.5
				turretPath="[0]";
			};
		};
	};
};

Global Variables:
----------------
There are two global variables you may or may not find useful.

 BD_MgFix_Init		- boolean
			whether or not MgFix has been initialized locally (false for
			clients who do not have MgFix installed locally)

 BD_MgFix_OnServer	- boolean
			true (for all clients) if MgFix is running on the server
			

Multiplayer:
===========
As of v1.4 this addon should be fully MP compatable. The addon need only be installed on the server, and the changes will be applied
for all clients. If the addon is not installed on the server, it will be disabled for all clients, regardless of whether they have it installed.

As of v2.0, full JIP compatability should also be present. The addon still need only be installed on the server, and must be installed on the
server.

Expansions:
===========
BD MultiGunFix v2.0 fully supports both ArmA 2 and ArmA 2: Operation Arrowhead. It does not require either, and will
work on ArmA 2 stand alone, OA stand alone, or ArmA 2: Combined Operations (ArmA 2 + OA).
Note: some features/functionality will only be available in OA.

As of v2.5 however, this addon may not work in standalone ArmA 2. See the requirements below for details.

Requirements:
=============
THIS ADDON REQUIRES EXTENDED EVENTHANDLERS
This addon should also be compatable with any other addons provided they don't interfere with the XEH stuff.

AS OF VERSION 2.5 THIS ADDON REQUIRES BUILD 74094 OF OA OR GREATER
Specifically, this change:
[73642]  New: event handler "fired" returns magazine name and object of projectile.
This means this addon WILL NOT WORK in regular ArmA 2 unless/until this change is added in a future patch.

Disclaimer:
==========
I am not responsible for ANYTHING that happens to your computer by using this addon. Use at your own risk.

Installation:
============
Install the pbo & bisign files into the Addons folder in your ArmA 2/OA directory or any mod directory. Install the
bikey file in your Keys directory.
